OneSpan Developer: Intelligent Adaptive Authentication - User Registration
OneSpan Intelligent Adaptive Authentication (IAA) provides a user registration REST API for the Sandbox environment, to let you smoothly integrate the user registration functionality within your web or mobile application. In this article, we will explore the user registration API which resides in the OneSpan IAA Interactive Sandbox API. Check out our previous blog “Intelligent Adaptive Authentication Sandbox API Intro” for an introduction of the IAA Sandbox API.
Before We Begin
Prior to exploring the user registration API, you must first be a OneSpan Community member and sign up for a free Intelligent Adaptive Authentication sandbox account. Check out this blog for instructions on how to do so.
Introduction
The user registration API allows you to provision a new user account for OneSpan Intelligent Adaptive Authentication and automatically assign an authenticator to that newly created user account. Provisioning a user instance on the OneSpan Risk Analytics is essential for leveraging the IAA comprehensive features.
Navigate to the User Registration Interactive API
In order to experiment with the user registration API, navigate to the IAA Sandbox Interactive API of your OneSpan Community account. In the Open API Swagger editor, expand the “Provisioning” resource. You will then find an entry for the user registration HTTP Post method as in the image below.
Example of the Structure of the User Registration API URL
The request URL for this API call will resemble the one below
https://{your_tenant_ID}.sdb.tid.onespan.cloud/v1/users/register
You won’t need to provide this URL during this tutorial, it is only for reference. The URL will be automatically assigned in the Interactive API when calling the web service.
User Registration API Request Body
Under the “Request Body” section of User Register endpoint, select "AdaptiveRegisterUserInput" object type from the dropped down menu as shown below. This object type is used to create a new user for the purpose of using the IAA activities. You will then get an example of the JSON payload for the registration request. The request will be populated with the JSON objects, which are required by the API of the "AdaptiveRegisterUserInput" object type.
The request body will look like the example below of the “users/register” endpoint’s required fields.
Request Payload
{
"objectType": "AdaptiveRegisterUserInput",
"cddc": {
"browserCDDC": {
"fingerprintRaw": "{browser:{\"userAgent\":Mozilla/5.0
(Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/65.0.3325.181 Safari/537.36},
support:{\"ajax\":true,\"boxModel\":undefined,
\"changeBubbles\":undefined,\"checkClone\":true,
\"checkOn\":true,\"cors\":true,
\"cssFloat\":undefined,\"hrefNormalized\":undefined,
\"htmlSerialize\":undefined,\"leadingWhitespace\":undefined,
\"noCloneChecked\":true,\"noCloneEvent\":undefined,
\"opacity\":undefined,\"optDisabled\":undefined,
\"style\":undefined,\"submitBubbles\":undefined,
\"tbody\":undefined},computer:{\"screenWidth\":2560,
\"screenHeight\":1440,\"OS\":\"Microsoft Windows\",
\"platform\":\"Win32\"}, additional:{}}",
"fingerprintHash": "e96dadc9651f5fe8f071110eb174fe8e7a17a9d7a96b3b1980c13e5b4af3a4d7"
}
},
"clientIP": "192.168.0.1",
"relationshipRef": "userid1",
"staticPassword": "Test1234",
"sessionID": "4ED23EA44F23",
"userID": "userid1"
}
Request Payload’s Required Fields’ Description
JSON Required Data Fields | Description | Fields Data Type |
---|---|---|
cddc* |
Client Device Data Collector meta data. The two fields browserCDDC and mobileCDDC are mutually exclusive and collectively exhaustive |
Type: string Example: “browserCDDC” or “mobileCDDC” |
relationshipRef* | The Relationship reference of the user ID |
Type: string |
staticPassword* | The initial static password assigned to the user. |
Type: string |
sessionID* | Application session identifier formatted as a hexadecimal string; common for all transactions related to the same session. |
Type: string |
userID* | A unique identifier for the user to be registered in the system. |
Type: string |
Calling the User Registration Endpoint
It is now time to send the request and register the user for OneSpan IAA. To make the API call, click on the “Try it out” button shown in the screenshot below, on the right side of the “/users/register” Post method section. Once requested, you will receive the response body back in a JSON format. It will be similar to the response payload described in the following section.
User Registration API Call Response Body:
Below is an example of returned response body of the “/users/register” API call.
{
"activationPassword": "xK384IF4",
"serialNumber": "VDS0064137",
"riskResponseCode": 0
}
Response Payload Fields Description
activationPassword
: The activation password that will be used later to activate the authenticator on the end user trusted device.
serialNumber
: The serial number of the authenticator which is automatically assigned to the new user instance.
riskResponseCode
: The response code that is specific and returned OneSpan Risk Analytics.
Once the registration process is completed, you will receive a response body similar to the example above with a 200 response code, which indicates the successful registration of a new user for the IAA Sandbox environment.
In this blog, we described how to register a new user using the IAA Sandbox Interactive API. We have also explored the structure and seen examples of the request and the response payloads, which are required by the “/users/register” endpoint. If you have any questions regarding this tutorial, feel free to reach us on the OneSpan Community Portal Forums.